home *** CD-ROM | disk | FTP | other *** search
/ Best Tools for JAVA / Best Tools for JAVA.iso / JAVA_ALL / JDBC / JDBC_011 / JDBC-011.ZIP / jdbc / java / sql / CallableStatement.java next >
Encoding:
Java Source  |  1996-11-10  |  9.5 KB  |  241 lines
  1. /*
  2.  * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
  3.  *
  4.  * Permission to use, copy, modify, and distribute this software
  5.  * and its documentation for NON-COMMERCIAL purposes and without
  6.  * fee is hereby granted provided that this copyright notice
  7.  * appears in all copies. Please refer to the file "LICENSE"
  8.  * for further important copyright and licensing information.
  9.  *
  10.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  11.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  12.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  13.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  14.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  15.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  16.  * 
  17.  * THIS SOFTWARE IS NOT DESIGNED OR INTENDED FOR USE OR RESALE AS ON-LINE
  18.  * CONTROL EQUIPMENT IN HAZARDOUS ENVIRONMENTS REQUIRING FAIL-SAFE
  19.  * PERFORMANCE, SUCH AS IN THE OPERATION OF NUCLEAR FACILITIES, AIRCRAFT
  20.  * NAVIGATION OR COMMUNICATION SYSTEMS, AIR TRAFFIC CONTROL, DIRECT LIFE
  21.  * SUPPORT MACHINES, OR WEAPONS SYSTEMS, IN WHICH THE FAILURE OF THE
  22.  * SOFTWARE COULD LEAD DIRECTLY TO DEATH, PERSONAL INJURY, OR SEVERE
  23.  * PHYSICAL OR ENVIRONMENTAL DAMAGE ("HIGH RISK ACTIVITIES").  SUN
  24.  * SPECIFICALLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS FOR
  25.  * HIGH RISK ACTIVITIES.
  26.  */
  27.  
  28. package java.sql;
  29.  
  30. /**
  31.  * <P>CallableStatement is used to execute SQL stored procedures.
  32.  *
  33.  * <P>JDBC provides a stored procedure SQL escape that allows stored
  34.  * procedures to be called in a standard way for all RDBMS's. This
  35.  * escape syntax has one form that includes a result parameter and one
  36.  * that does not. If used, the result parameter must be registered as
  37.  * an OUT parameter. The other parameters may be used for input,
  38.  * output or both. Parameters are refered to sequentially, by
  39.  * number. The first parameter is 1.
  40.  *
  41.  * <P><CODE>
  42.  * {?= call <procedure-name>[<arg1>,<arg2>, ...]}<BR>
  43.  * {call <procedure-name>[<arg1>,<arg2>, ...]}
  44.  * </CODE>
  45.  *    
  46.  * <P>IN parameter values are set using the set methods inherited from
  47.  * PreparedStatement. The type of all OUT parameters must be
  48.  * registered prior to executing the stored procedure; their values
  49.  * are retrieved after execution via the get methods provided here.
  50.  *
  51.  * <P>A Callable statement may return a ResultSet or multiple
  52.  * ResultSets. Multiple ResultSets are handled using operations
  53.  * inherited from Statement.
  54.  *
  55.  * <P>For maximum portability, a call's ResultSets and update counts
  56.  * should be processed prior to getting the values of output
  57.  * parameters.
  58.  *
  59.  * @see Connection#prepareCall
  60.  * @see ResultSet 
  61.  */
  62. public interface CallableStatement extends PreparedStatement {
  63.  
  64.     /**
  65.      * Before executing a stored procedure call, you must explicitly
  66.      * call registerOutParameter to register the java.sql.Type of each
  67.      * out parameter.
  68.      *
  69.      * <P><B>Note:</B> When reading the value of an out parameter, you
  70.      * must use the getXXX method whose Java type XXX corresponds to the
  71.      * parameter's registered SQL type.
  72.      *
  73.      * @param parameterIndex the first parameter is 1, the second is 2,...
  74.      * @param sqlType SQL type code defined by java.sql.Types;
  75.      * for parameters of type Numeric or Decimal use the version of
  76.      * registerOutParameter that accepts a scale value
  77.      * @see Type 
  78.      */
  79.     void registerOutParameter(int parameterIndex, int sqlType)
  80.         throws SQLException;
  81.  
  82.     /**
  83.      * Use this version of registerOutParameter for registering
  84.      * Numeric or Decimal out parameters.
  85.      *
  86.      * <P><B>Note:</B> When reading the value of an out parameter, you
  87.      * must use the getXXX method whose Java type XXX corresponds to the
  88.      * parameter's registered SQL type.
  89.      *
  90.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  91.      * @param sqlType use either java.sql.Type.NUMERIC or java.sql.Type.DECIMAL
  92.      * @param scale a value greater than or equal to zero representing the 
  93.      *              desired number of digits to the right of the decimal point
  94.      * @see Type 
  95.      */
  96.     void registerOutParameter(int parameterIndex, int sqlType, int scale)
  97.         throws SQLException;
  98.  
  99.     /**
  100.      * An OUT parameter may have the value of SQL NULL; wasNull reports 
  101.      * whether the last value read has this special value.
  102.      *
  103.      * <P><B>Note:</B> You must first call getXXX on a parameter to
  104.      * read its value and then call wasNull() to see if the value was
  105.      * SQL NULL.
  106.      *
  107.      * @return true if the last parameter read was SQL NULL 
  108.      */
  109.     boolean wasNull() throws SQLException;
  110.  
  111.     /**
  112.      * Get the value of a CHAR, VARCHAR, or LONGVARCHAR parameter as a Java String.
  113.      *
  114.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  115.      * @return the parameter value; if the value is SQL NULL, the result is null
  116.      */
  117.     String getString(int parameterIndex) throws SQLException;
  118.  
  119.     /**
  120.      * Get the value of a BIT parameter as a Java boolean.
  121.      *
  122.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  123.      * @return the parameter value; if the value is SQL NULL, the result is false
  124.      */
  125.     boolean getBoolean(int parameterIndex) throws SQLException;
  126.  
  127.     /**
  128.      * Get the value of a TINYINT parameter as a Java byte.
  129.      *
  130.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  131.      * @return the parameter value; if the value is SQL NULL, the result is 0
  132.      */
  133.     byte getByte(int parameterIndex) throws SQLException;
  134.  
  135.     /**
  136.      * Get the value of a SMALLINT parameter as a Java short.
  137.      *
  138.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  139.      * @return the parameter value; if the value is SQL NULL, the result is 0
  140.      */
  141.     short getShort(int parameterIndex) throws SQLException;
  142.  
  143.     /**
  144.      * Get the value of an INTEGER parameter as a Java int.
  145.      *
  146.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  147.      * @return the parameter value; if the value is SQL NULL, the result is 0
  148.      */
  149.     int getInt(int parameterIndex) throws SQLException;
  150.  
  151.     /**
  152.      * Get the value of a BIGINT parameter as a Java long.
  153.      *
  154.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  155.      * @return the parameter value; if the value is SQL NULL, the result is 0
  156.      */
  157.     long getLong(int parameterIndex) throws SQLException;
  158.  
  159.     /**
  160.      * Get the value of a FLOAT parameter as a Java float.
  161.      *
  162.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  163.      * @return the parameter value; if the value is SQL NULL, the result is 0
  164.      */
  165.     float getFloat(int parameterIndex) throws SQLException;
  166.  
  167.     /**
  168.      * Get the value of a DOUBLE parameter as a Java double.
  169.      *
  170.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  171.      * @return the parameter value; if the value is SQL NULL, the result is 0
  172.      */
  173.     double getDouble(int parameterIndex) throws SQLException;
  174.  
  175.     /**
  176.      * Get the value of a NUMERIC parameter as a java.lang.Bignum object.
  177.      *
  178.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  179.      * @param scale a value greater than or equal to zero representing the 
  180.      *              desired number of digits to the right of the decimal point
  181.      * @return the parameter value; if the value is SQL NULL, the result is null
  182.      */
  183.     Bignum getBignum(int parameterIndex, int scale) throws SQLException;
  184.  
  185.     /**
  186.      * Get the value of a SQL BINARY or VARBINARY parameter as a Java byte[]
  187.      *
  188.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  189.      * @return the parameter value; if the value is SQL NULL, the result is null
  190.      */
  191.     byte[] getBytes(int parameterIndex) throws SQLException;
  192.  
  193.     /**
  194.      * Get the value of a SQL DATE parameter as a java.sql.Date object
  195.      *
  196.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  197.      * @return the parameter value; if the value is SQL NULL, the result is null
  198.      */
  199.     java.sql.Date getDate(int parameterIndex) throws SQLException;
  200.  
  201.     /**
  202.      * Get the value of a SQL TIME parameter as a java.sql.Time object.
  203.      *
  204.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  205.      * @return the parameter value; if the value is SQL NULL, the result is null
  206.      */
  207.     java.sql.Time getTime(int parameterIndex) throws SQLException;
  208.  
  209.     /**
  210.      * Get the value of a SQL TIMESTAMP parameter as a java.sql.Timestamp object.
  211.      *
  212.      * @param parameterIndex the first parameter is 1, the second is 2, ...
  213.      * @return the parameter value; if the value is SQL NULL, the result is null
  214.      */
  215.     java.sql.Timestamp getTimestamp(int parameterIndex) 
  216.         throws SQLException;
  217.  
  218.     //----------------------------------------------------------------------
  219.     // Advanced features:
  220.  
  221.  
  222.     /**
  223.      * Get the value of a parameter as a Java object.
  224.      *
  225.      * <p>This method returns a Java object whose type coresponds to the SQL
  226.      * type that was registered for this parameter using registerOutParameter.
  227.      *
  228.      * <p>Note that this method may be used to read
  229.      * datatabase-specific, abstract data types. This is done by
  230.      * specifying a targetSqlType of java.sql.types.OTHER, which
  231.      * allows the driver to return a database-specific Java type.
  232.      *
  233.      * @param parameterIndex The first parameter is 1, the second is 2, ...
  234.      * @return A java.lang.Object holding the OUT parameter value.
  235.      * @see Types 
  236.      */
  237.     Object getObject(int parameterIndex) throws SQLException;
  238.  
  239. }
  240.  
  241.